\documentclass[10pt]{article}
\usepackage{fullpage}

\begin{document}

\title{Using NNexus the Pitman Way}
\author{James Gardner}
\date{\today}
\maketitle


{\bf This document outlines using the scripts developed for Dr. Pitman for his
Probability Course Notes}

{\bf This document assumes that a working version of NNexus and latex2html are already installed.}

\section{Utilities Covered}
The utilities developed for Dr. Pitman include the following scripts.
\begin{itemize}
\item \verb#linkingclient.pl# - simply sends nnexus xml to the server and waits for the response.
\item \verb#latex2nnexus.pl# - converts a latex (.tex) file to the correct format for NNexus and returns a linked version of the same latex file.

\item \verb#render_notes.pl# - traverses and entire directory tree of latex files,
links them, renders them (with latex2html) and places them in an output directory tree. \verb#render_notes.pl# also builds an index linking to the output directory tree.

\item \verb#buildIndex.pl# - traverses a directory tree and provides a link
to all tex files in the directory that have already been processed by latex2html

\item \verb#pitman2nnexusxml.pl# - converts a directory into NNexus XML format for
adding to the NNexus database.
\end{itemize}

\section{Quick and Dirty}
This Quick and Dirty section describes the process of linking a directory of lecture notes with NNexus and rendering them in html form. Note: This section assumes that all domain information and article information is already imported into NNexus.

The steps are:
\begin{enumerate}
\item Make sure the directory containing the \verb#.tex# files does not contain any \verb#.tex# files with spaces in the filename. (This is required for latex2html to process the files correctly). The \verb#whitespacerm.sh# bash script will ensure that the filenames are in the correct format. To use
\verb#whitespacerm.sh# copy it into the directory you wish to remove the whitespaces and execute \verb#sh whitespacerm.sh#.

\noindent {\bf Example}
Suppose you have a directory with the following files:
\begin{verbatim}
Frodo:~/Desktop/Research/pitman/trunk/example$ ls
Densities.tex                   Double or Nothing_game.tex
Doob's maximal inequality       
\end{verbatim}

Copy \verb#whitespacerm.sh# into \verb#Frodo:~/Desktop/Research/pitman/trunk/example#
and execute

\begin{verbatim}
Frodo:~/Desktop/Research/pitman/trunk/example$ sh whitespacerm.sh 
Densities.tex Densities.tex
Doob's maximal inequality Doob_s_maximal_inequality
Double or Nothing game.tex Double_or_Nothing_game.tex
whitespacerm.sh whitespacerm.sh
\end{verbatim}

You will then have
\begin{verbatim}
Frodo:~/Desktop/Research/pitman/trunk/example$ ls
Densities.tex                   Double_or_Nothing_game.tex
Doob_s_maximal_inequality       whitespacerm.sh
\end{verbatim}

\item Run \verb#render_notes.pl <input_path> <output_path>.#
This will link and render all .tex files into \verb#<output_path>/<input_path># preserving the directory structure of \verb#<input_path>#.

\noindent {\bf Example}
\begin{verbatim}
Frodo:~/Desktop/Research/pitman/trunk dryice$ perl render_notes.pl example/ ./examplelinked
processing example tree to ./examplelinked tree
------------------------------------
linking traversal
------------------------------------
*** processing all .tex files in example
*** copying latex2html-init and macros-topic.tex to ./examplelinked/example//
linking tex file: example/Densities.tex and creating it at ./examplelinked/example/Densities.tex
linking tex file: example/Double_or_Nothing_game.tex and creating it at ./examplelinked/example/Double_or_Nothing_game.tex
------------------------------------
rendering traversal
------------------------------------
copying Densities.tex to Densities.tex with latex2html hacks*** rendering html for file: ./examplelinked/example/Densities.tex
*** this will take some time ...
texexpand V2002-2-1 (Revision 1.11)

.
.
.
.
\end{verbatim}

You can then view the output by opening any of the html files in the output path.


\item Build a ``pretty'' index using \verb#buildIndex.pl#

\noindent {\bf Example}
\begin{verbatim}
Frodo:~/Desktop/Research/pitman/trunk dryice$ perl buildIndex.pl ./examplelinked/
processing ./examplelinked tree
linking tex file: ./examplelinked/example/Densities.tex and creating it at ./examplelinked/example/Densities.tex
Density
linking tex file: ./examplelinked/example/Double_or_Nothing_game.tex and creating it at ./examplelinked/example/Double_or_Nothing_game.tex
Double or Nothing Game
writing html index to ./examplelinked/testindex.html
\end{verbatim}

You will then need to copy the testindex.html to the top level directory of the rendered directory structure. In this example it is 
\verb#Frodo:~/Desktop/Research/pitman/trunk#

\item Copy the newly created directory into the correct location according to your domain configuration file in NNexus.

More details on this are to come.
\end{enumerate}

After the above steps you should be able to view the notes from your browser and all links should work correctly.

\section{Adding Notes To NNexus Server}
Adding notes to the NNexus server is easy using \verb#pitman2nnexusxml.pl#.
To add a directory of \verb#.tex# files to the NNexus server run
\verb#pitman2nnexusxml.pl <directory_name>#. This script pulls the meta-data
from the all the .tex files in \verb#<directory_name># (and all sub-directories) and 
creates an xml file called pitmanout.xml that can be sent to the NNexus server for adding the
concepts.

\end{document}
